使用 ASP.NET Core 控制器创建 Web API

创建 Web API 项目

使用dotnet new webapi创建 Web API 项目

$ dotnet new webapi -controllers -o HelloWebAPI
已成功创建模板“ASP.NET Core Web API”。

正在处理创建后操作...
正在还原 D:\dotnet\HelloWebAPI\HelloWebAPI.csproj:
  正在确定要还原的项目…
  已还原 D:\dotnet\HelloWebAPI\HelloWebAPI.csproj (用时 4.3 秒)。
已成功还原。

此命令使用别名为 webapi 的 ASP.NET Core 项目模板来搭建基于 C# 的 Web API 项目的基架。 将创建一个 HelloWebAPI 目录。 此目录包含在 .NET 上运行的 ASP.NET Core 项目。 项目名称与 HelloWebAPI 目录名称匹配。

现在应该可以访问以下文件和目录：

-| Controllers
-| obj
-| Properties
-| appsettings.Development.json
-| appsettings.json
-| HelloWebAPI.csproj
-| HelloWebAPI.http
-| Program.cs
-| WeatherForecast.cs

检查以下文件和目录：

名称	描述
Controllers/	包含公共方法公开为 HTTP 终结点的类。
Program.cs	配置服务和应用的 HTTP 请求管道，包含应用的托管入口点。
HelloWebAPI.csproj	包含项目的配置元数据。
HelloWebAPI.http	包含直接从 Visual Studio Code 测试 REST API 的配置。

生成并测试 Web API

1. 在命令行界面中运行以下 .NET Core CLI 命令：

$ cd HelloWebAPI
$ dotnet run
正在生成...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5168
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: D:\dotnet\HelloWebAPI

上述命令：

• 在当前目录中找到项目文件。
• 检索并安装此项目所需的任何项目依赖项。
• 编译项目代码。
• 使用 ASP.NET Core Kestrel Web 服务器将 Web API 托管在 HTTP 终结点中。

创建项目时，将为 HTTP 选择 5000 到 5300 端口，为 HTTPS 选择 7000 到 7300 端口。 通过编辑项目的 launchSettings.json 文件，可以轻松更改开发过程中使用的端口。

2. 打开 Web 浏览器并转到：

http://localhost:5168/weatherforecast

应会看到类似于这个示例的 JSON 输出：

[
  {
    "date": "2025-03-16",
    "temperatureC": -5,
    "temperatureF": 24,
    "summary": "Scorching"
  },
  {
    "date": "2025-03-17",
    "temperatureC": 51,
    "temperatureF": 123,
    "summary": "Cool"
  },
  {
    "date": "2025-03-18",
    "temperatureC": -3,
    "temperatureF": 27,
    "summary": "Bracing"
  },
  {
    "date": "2025-03-19",
    "temperatureC": 33,
    "temperatureF": 91,
    "summary": "Balmy"
  },
  {
    "date": "2025-03-20",
    "temperatureC": -15,
    "temperatureF": 6,
    "summary": "Sweltering"
  }
]

ASP.NET Core Web API 控制器

using Microsoft.AspNetCore.Mvc;

namespace HelloWebAPI.Controllers;

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

基类：ControllerBase

控制器是一个公共类，具有一个或多个称为“操作”的公共方法。 按照惯例，控制器放在项目根目录的 Controllers 目录中。 操作通过路由被公开为 HTTP 终结点。 因此，对 https://localhost:{PORT}/weatherforecast 的 HTTP GET 请求将执行 WeatherForecastController 类的 Get() 方法。

首先要注意的是，此类继承自 ControllerBase 基类。 这个基类提供了许多用于处理 HTTP 请求的标准功能，让你可以专注于应用程序的特定业务逻辑。

WARNING

如果你在 ASP.NET Core 中开发过 Razor Pages 或模型-视图-控制器 (MVC) 体系结构，那么你已使用过 Controller 类。 不要通过从 Controller 类派生来创建 Web API 控制器。 Controller 派生自 ControllerBase，并添加了对视图的支持，因此它用于处理网页，而不是 Web API 请求。

API 控制器类属性

有两个重要属性应用到了 WeatherForecastController，如以下代码所示：

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

[ApiController] 启用固定行为，使生成 Web API 更加容易。 一些行为包括参数源推理、将属性路由作为一项要求以及模型验证错误处理增强功能*。

[Route] 定义路由模式 [controller]。 [controller] 令牌替换为用控制器的名称（不区分大小写，无 Controller 后缀）。 此控制器处理对 https://localhost:{PORT}/weatherforecast 的请求。

使用 Get() 方法提供天气预报结果

WeatherForecastController 包括由 [HttpGet(Name = "GetWeatherForecast")] 属性指定的单个控制器操作。 此属性将 HTTP GET 请求路由到 public IEnumerable<WeatherForecast> Get() 方法。 向 https://localhost:{PORT}/weatherforecast 发出请求会导致返回天气预报结果。